SurePassID Offline OTP Cheat Sheet

SurePassID Authentication Server

Offline OTP Cheat Sheet

Quick reference for the offline OTP / offline-code cache flow. Full details: OfflineOTP-and-CacheUpdate

TL;DR

On a successful online validation of an event/HOTP token, the server advances the token counter, persists it, then pre-generates the next N HOTP codes and returns them so the offline client can validate locally while disconnected.

Endpoints

All OTP paths call AuthServerApi.ValidateOtpOfflineCodes(...).

ocodes / OCODES values

Success response

Legacy ValidateOTP.aspx:

0000
OK
<OcraServerCode>
<OfflineCodes>   <- comma-separated: "483920,118273,900142,..."

JSON: ValidateOathOtpResponse.offlineCodes (omitted when empty).

What happens on a match (event/HOTP token)

1. device.LastOTPValidation = now
2. NextCounter++              (consume matched code)
3. UpdateDevice(...)          (persist advanced counter)
4. GenerateOffLineCodeDevice(...)   (rebuild cache from NEW counter)
5. (opt) mirror counter to virtual token

• Returned codes start at the new NextCounter -> the used code is never re-issued.
• Persisted NextCounter keeps server + client cache in sync.

Codes are generated only when...

• Device is Enabled, AND
• Device type is event/offline based: Event, Event256, Event512, OffLine, DynamicCvcEvent.

Codes are standard HOTP (RFC 4226) using the token's OTPLength + hash from OTP type. Multi-device: stops at the first device that can generate codes.

Config switches

(Code count is per-request, not a server config.)

FIDO offline (PreSign.aspx?...&OFF=1)

No HOTP codes — returns U2F sign material plus the app's ECC-256 public cert (AppIdECC256PublicCertB64) so the agent verifies signatures offline.

Fast test checks

• Valid OTP + ocodes=N -> success + exactly N codes.
• NextCounter advanced by 1; first returned code = HOTP(secret, NextCounter).
• ocodes=0 -> empty; ocodes=-1 -> count = OTPWindowSize.
• Non-event/disabled token -> no codes.
• FIDO OFF=1 -> extra ECC-256 cert line.

Key files

• AuthServerApiOtp.cs -> ValidateOtpOfflineCodes, ValidateOtpInternal, GenerateOffLineCodeDevice, GenerateOffLineCodes
• server/ApiActions/ValidateOtp.cs, CreateServerChallenge.cs
• server/Models/ValidateOathOtpResponse.cs
• AuthServer/ValidateOTP.aspx.cs, AuthServer/PreSign.aspx.cs